/**
 * 
 */
package org.yelongframework.model.support.mybatis.sql.executor;

import java.util.List;
import java.util.Map;

import org.apache.ibatis.session.SqlSession;
import org.yelongframework.lang.Nullable;
import org.yelongframework.model.support.mybatis.mapper.GenericMapperParamBuilder;
import org.yelongframework.model.support.mybatis.sql.MybatisParamMap;
import org.yelongframework.mybatis.mapper.GenericMapper;
import org.yelongframework.sql.SqlRuntimeException;
import org.yelongframework.sql.executor.SqlExecutor;

/**
 * Mybatis实现的SQL执行器
 * 
 * @since 1.0.0
 */
public interface MybatisSqlExecutor extends SqlExecutor {

	// ==================================================执行SQL返回执行行数==================================================

	/**
	 * 执行数据库操作
	 * 
	 * @param sql             SQL语句,该SQL为mybatis类型的SQL（参数占位符为#{}类型）
	 * @param mybatisParamMap 参数。支持为空
	 * @return 操作的记录数
	 * @throws SqlRuntimeException SQL运行异常
	 */
	Integer executeUpdate(String sql, @Nullable MybatisParamMap mybatisParamMap) throws SqlRuntimeException;

	// ==================================================执行查询==================================================

	/**
	 * 执行数据库查询。
	 * 
	 * @param sql             SQL语句,该SQL为mybatis类型的SQL（参数占位符为#{}类型）
	 * @param mybatisParamMap 参数。支持为空
	 * @return 查询的数据集合。没有记录这将是一个空的集合
	 * @throws SqlRuntimeException SQL运行异常
	 */
	List<Map<String, Object>> executeQuery(String sql, @Nullable MybatisParamMap mybatisParamMap)
			throws SqlRuntimeException;

	/**
	 * 查询一行记录
	 * 
	 * @param sql             SQL语句,该SQL为mybatis类型的SQL（参数占位符为#{}类型）
	 * @param mybatisParamMap 参数。支持为空
	 * @return 一条数据的键值对。没有记录这将返回null
	 * @throws SqlRuntimeException SQL运行异常
	 */
	Map<String, Object> executeQueryRow(String sql, @Nullable MybatisParamMap mybatisParamMap)
			throws SqlRuntimeException;

	/**
	 * 查询一列数据
	 * 
	 * @param sql             SQL语句,该SQL为mybatis类型的SQL（参数占位符为#{}类型）
	 * @param mybatisParamMap 参数。支持为空
	 * @return 数据的集合
	 * @throws SqlRuntimeException SQL运行异常
	 */
	<T> List<T> executeQueryColumn(String sql, @Nullable MybatisParamMap mybatisParamMap) throws SqlRuntimeException;

	/**
	 * 查询唯单一的数据值
	 * 
	 * @param <T>             data type
	 * @param sql             SQL语句,该SQL为mybatis类型的SQL（参数占位符为#{}类型）
	 * @param mybatisParamMap 参数。支持为空
	 * @return 查询的唯一值
	 * @throws SqlRuntimeException SQL运行异常
	 */
	<T> T executeQuerySingleObject(String sql, @Nullable MybatisParamMap mybatisParamMap) throws SqlRuntimeException;

	/**
	 * 查询数据库记录数
	 * 
	 * @param sql             SQL语句,该SQL为mybatis类型的SQL（参数占位符为#{}类型）
	 * @param mybatisParamMap 参数。支持为空
	 * @return 查询数据总数。查询的第一行第一列的Long类型值。
	 * @throws SqlRuntimeException SQL运行异常
	 */
	Long executeQueryCount(String sql, @Nullable MybatisParamMap mybatisParamMap) throws SqlRuntimeException;

	// ==================================================通用映射器==================================================

	/**
	 * @return 通用映射器
	 */
	GenericMapper getGenericMapper();

	/**
	 * @return 通用映射器参数构建器
	 */
	GenericMapperParamBuilder getGenericMapperParamBuilder();

	// ==================================================SQL会话==================================================

	/**
	 * @return SqlSession
	 * @throws SqlRuntimeException SQL运行异常
	 */
	SqlSession getSqlSession() throws SqlRuntimeException;

}
